|
|
PostHighLevelEvent |
||||
| Header: | EPPC.h | Carbon status: | Unsupported | |
Sends a high-level event to another application.
OSErr PostHighLevelEvent (
const EventRecord *theEvent,
void *receiverID,
UInt32 msgRefcon,
void *msgBuff,
UInt32 msgLen,
UInt32 postingOptions
);
A pointer to the event structure for the event to send. Your application should fill out the what, message, and where fields of the event structure. Specify the kHighLevelEvent constant in the what field, the event class of the high-level event in the message field, and the event ID in the where field. You do not need to fill out the when or modifiers fields; the Event Manager automatically assigns the appropriate values to these fields when you send the message.
The recipient of the high-level event. When sending an event to another application on the local computer, you can specify the recipient of the event by session reference number, process serial number, signature, or port name and location name. When sending an event to an application on a remote computer, you can specify the recipient only by the session reference number or by the port name and location name.
To specify a port name and location name, provide the address of a target ID structure in the receiverID parameter. To specify a process serial number, provide its address in the receiverID parameter. To specify a session reference number, or signature, provide the data in the receiverID parameter.
A unique number that identifies the communication associated with this event. Your application can set this field to any value it chooses. If you are replying to a high-level event, you should use the same value in the msgRefcon parameter as specified in the high-level event that originated the request.
A pointer to a data buffer that contains any additional data for the event.
The size (in bytes) of the data buffer pointed to by the msgBuff parameter.
Options associated with the receiverID parameter and delivery options associated with the event. You can specify one or more delivery options to indicate whether you want the other application to receive the event at the next opportunity and to indicate whether you want acknowledgment that the event was received by the other application. You use the options associated with the receiverID parameter to indicate how you are specifying the recipient of the event—whether by port name and location name in a target ID structure, by session reference number, by process serial number, or by signature.
For descriptions of the enumerators you can use to specify posting options, see
A result code.
The PostHighLevelEvent function posts the high-level event to the specified process.
If the application to which you are sending a high-level event terminates, you receive the result code sessionClosedErr the next time your application calls PostHighLevelEvent to send another high-level event to the terminated application. If you do not care about any state information about that session, you can just resend your event. Otherwise, you must restart another session and resend your event.
If your application is running in the background and posts a high-level event that requires the network authentication dialog box to be displayed, PostHighLevelEvent returns the noUserInteractionAllowed result code, does not display the network authentication dialog box, and does not send the event. If your application receives the noUserInteractionAllowed result code, you can use the Notification Manager to inform the user that your application needs attention. When the user brings your application to the foreground, you can repost the event. If the reposting is successful, your application can continue to post high-level events without further user interaction. Note that PostHighLevelEvent can return noUserInteractionAllowed only on the first posting of a high-level event to a remote target.
The PostHighLevelEvent function may move or purge memory. You should not call this function from within an interrupt, such as in a completion function or VBL task.
Not supported in Carbon. Not available in Carbon.
The High Level Event APIs (EPPC.h) are not supported in Carbon. Instead, use Apple events.
© 2000 Apple Computer, Inc. — (Last Updated 5/8/2000)